InfoMagic Internet Tools 1993 July

home *** CD-ROM | disk | FTP | other *** search

/ InfoMagic Internet Tools 1993 July / Internet Tools.iso / RockRidge / ip / manage / snmp / kip / doc / install < prev next >

Wrap

Text File | 1989-01-17 | 26.5 KB | 598 lines

KIP INSTALLATION INSTRUCTIONS (6/88) To install and run the KIP gateway code involves the following steps: Transfer the gateway source/binary files to a (UNIX) host. Compile gateway programs. Setup admin daemon and database. Edit /etc/atalk.local. Transfer gw.srec and prompt.config from UNIX to a Mac disk. Run Kinetics 'FastPath Manager' program to download gateway. Test gateway with 'ping' and 'ddt', 'chooser'. Install CAP with mods. Obtain and try out MacIP programs. TRANSFER FILES There are a number of files needed to use this gateway. You can either FTP these files if you have internet access, or (I believe) Kinetics Users Group will have SONY disks available containing the same information for a nominal copy fee. The following files are in the <info-mac> directory on sumex-aim.stanford.edu. The file names are prefixed with 'at-' in the directory to set them apart from other info-mac files. Use login name 'anonymous' with FTP. kip.shar gateway and daemon source gw.srec latest gateway 'binary' in S-record hex format ddt.shar source for the network debugger. To obtain information about the Columbia University AppleTalk Package for Unix, send mail to capinfo@cunixc.columbia.edu (internet), columbia!cunixc!capinfo (uucp), or capinfo@cunixc.BITNET for more information. (A copy of CAP is also kept on <info-mac> at sumex under the at-cap* prefix). You don't have to compile any Macintosh or Kinetics source code unless you wish to. The file 'gw.srec' contains the latest gateway binary. If you DO want to compile you will need a 68000 C compiler that runs under UNIX. We use our 4.X BSD VAX with the compiler distributed with SUMacC. But you can also use 68000 UNIX boxes, for example Kinetics uses a Pyramid box. For VAX people you can FTP these files from sumex-aim.stanford.edu, login anonymous, directory <info-mac>. sumacc.tar 68000 C compiler plus Mac libraries; 2.5 megabytes. SUMacC hasnt changed since Nov 84, so this is not a 'new' version. (Also available from safe.stanford.edu). sumacc-rmaker.shar (dated Aug 85) sumacc-rmaker-v2.shar (dated Aug 86) Later versions of the Mac resource compiler; I believe the efs.tar used the first of these but they should be upward compatible. COMPILE GATEWAY PROGRAMS Dearchive at-kip.shar into UNIX directory 'kip'. The directory 'kip/etc' contains the following files: atalk.local sample host number database, copied to /etc atalkad.c appletalk admin daemon atalkrd.c appletalk rebroadcast daemon (not usually needed) atalkatab sample database for atalkad, copied to /etc b.out.h 68K object file format, used by dl68.c dl68.c binary to hex conversion utility used by SUMacC; or use native utility, such as 'hex'. Makefile makefile for C progs in this dir prompt.config sample config file used by Kinetics 'prompt' program The directory 'kip/doc' contains documentation files: install installation document broadcast document explaining broadcast terminology ip.at specification for IP on AppleTalk rev1086 documents revisions of the gateway rev0287 rev0987 rev0188 rev0688 stackdump how to interpret Kinetics stack dumps Typing 'make' in the 'kip/etc' directory will result in atalkad and other binaries being produced. The 'at-gw.srec' file that you obtained in the 'TRANSFER FILES' step can be directly downloaded to the gateway, so you can skip the gateway compile steps in the remainder of this section if you wish. (If so, skip to the next section 'APPLETALK FORMS'). The makefile in the top level 'kip' directory is setup for a VAX. Another file, makefile.68 can be used if you have a native 68000 UNIX; unfortunately your native assembler may not understand the MIT-style opcodes used. If so, find a VAX(!) If your machine doesnt support 'flexnames', edit the line in fp/kfps.h as shown: 14c14 < define(`flexnames') --- > |# define(`flexnames') If your UNIX prepends an '_' underscore in front of all C externals, remove the '-Dnoprepend' from the makefile. Now you should be able say 'make' and end up with a gw.srec file. Gw.sym is also produced from each load and contains the complete object file plus symbol table. The network debugger ddt was developed on a VAX and assumes the b.out.h object file header format produced by the MIT C compiler. This should be ifdefed for native compilers as well. If you are going to use ddt, fetch and dearchive it. Typing 'make' in that directory should result in a 'ddt' executable that can be copied to a directory such as /usr/local/bin. APPLETALK FORMS Before we can discuss setting up the administrator daemon and database (in the next section), we need to explain the different forms in which appletalk exists. 'Appletalk' is the word used by Apple to describe the protocol family that they designed. This protocol family contains protocols that implement various services such as name binding (location), file access, and laserwriter printing. The Appletalk protocol family can be used on a variety of communication media. For each of these media, appletalk takes on a unique 'form' (or encapsulation) specific to that media. Thus we can label three different appletalk-forms: 'Localtalk' is Appletalk on the original Apple-designed daisy-chain cabling system (shielded, twisted pair). Localtalk would also refer to the alternate cable scheme developed by Farallon (PhoneNet) that uses standard phone company cables and connectors. 'Ethertalk' is Appletalk running on ethernet hardware. There are now cards for the Mac II (from Apple/3com and Kinetics) that speak ethertalk. Additionally some commercial mainframe products such as TOPS for UNIX and Alisatalk for VMS use ethertalk. 'Appletalk-in-IP' is Appletalk encapsulated inside IP datagrams, which in turn are carried on a media such as ethernet or fiber optics. The advantage of putting appletalk inside of IP is that preexisting campus gateways and hosts dont have to be modified (at low levels) to understand appletalk. There is much more equipment available on the market that understands the IP protocol family versus the relatively new Appletalk family. For 4.X BSD derived UNIX machines, the CAP (Columbia Univ. Appletalk Package) software provides file access and print spooling capabilities. The original KIP gateway software supported the localtalk and appletalk-in-IP forms of appletalk. The 0188 release of KIP added the support of ethertalk. Thus a single ethernet cable can support both the ethertalk and the appletalk-in-IP encapsulations. This is done by assigning such ether cables TWO appletalk network numbers. Traffic directed to one of the net numbers goes out in ethertalk form, traffic to the other net number goes out as appletalk-in-IP. At a recent Apple sponsored IP conference, this mechanism was dubbed 'doubletalk'(!) You might encounter this confusion in terminology: before 1987 Apple Computer refered to the protocol family AND the physical cabling / signaling system as 'appletalk'. Just be aware that 'appletalk' NOW means the protocol family and not just a particular physical implementation such as localtalk or ethertalk. SETUP ATALKAD AND DATABASE The appletalk administrator daemon, /etc/atalkad, runs on only ONE of the UNIX hosts in your organization / department. So this document section will only be used by your campus appletalk administrator. Chdir to kip/etc, become su, and type 'make install' and 'make installonce'. The first install copies the daemon binary to /etc. The one-time only install copies atalkatab and atalk.local to /etc and starts off the log file in /usr/adm/atalkalog. You now need to edit the files /etc/atalkatab and /etc/atalk.local to correspond to your local network configuration. Print out and read over the comments in atalkatab to see the format of the data. In this example file, we show a campus using a class B network number, 128.222.s.h, where 128.222 is the class B net, 's' is the IP subnet number of the ethernet cable, and 'h' is host number on that cable. Remember that that there are no dependencies on subnets in the KIP gateway code, so this example showing subnets could just as easily have used separate class C numbers for the ethernet cables. In the example note that the 16 bit (two byte) appletalk net number (anet) can be written in 'dot notation', e.g. '55.13'. This means the upper byte of the anet is 55 and the lower byte is 13; these values are in decimal, so the maximum anet number would be 255.255. For appletalk-in-IP ethernet cables there is a relation between the IP address (combined net/host number) of a host on that cable, and the appletalk net/node numbers of the same host. The net number parts are totally different, but the low byte of the IP address (host number) corresponds exactly to the appletalk node number. The appletalk net and IP net numbers are only related by a line in the atalkatab file, mapping an appletalk net number to an IP net number. Now for administrative simplicity we have chosen to have three ranges of anet numbers. Anet numbers 55.XX will be used to represent appletalk-in-IP ether cables, where XX is set equal to the third byte of the IP address of that ether cable (i.e. the subnet number for class B nets or simply the 3rd byte of a class C number). And anet numbers 56.YY will be used to represent localtalk cables, where we just assign a new number YY starting at 1 for each new cable. Finally, anet numbers 57.ZZ are used to represent ethertalk cables. For your own situation you can use whatever scheme you wish: you could use other values than 55/56/57, or you could even decide to number all the cables in the same range. It's not important. With this background you should now be able to understand the sample file. The first three lines describe appletalk-in-IP ether cables. Note the 'N1' flag which means that this is an IP net number, and to form the broadcast address we add a single '.255' to the given IP address. Note that your main campus IP gateways must support directed broadcasts in one of these formats. If your net doesn't have directed broadcast capability: (1) convince your gateway vendor to put it in; (2) in the meantime you can use the 'H' flag in atalkatab. The kboxes can act as 'rebroadcast' servers; we also provide a program atalkrd.c (rebroadcast daemon) that can run on a 4.X BSD UNIX machine. The file 'doc/broadcast' explains this in more detail. After the first group of three lines in the sample atalkatab, there follows three groups of about eight lines each. Each of these groups describes an appletalk-in-IP ether cable containing a kbox, the localtalk cable / kbox, and then the configuration data for that kbox. Probably the best way to proceed would be to use one of these groups of seven as a template for your site. And then for each additional kbox at your site, dup your own template and further customize it. Of course you will want to delete or change all of the sample data we provide to correspond to your site only. Dont leave any of the provided sample entries in your actual database. In the following paragraph we describe the fields used in the current configuration information. The atalkad daemon is rather stupid when it comes to interpreting this data. It just treats the data as a byte stream that is shipped to the gateway; it has no knowledge of the format or legal values possible in these fields. So you have to be a little careful. That is why it is a good idea to dup an existing template as a model in editing in your own data. Note that each field is preceded by a data type indicator; it is very important to preserve this type selection byte. It also may be a little confusing, since the 'network description' line that preceeds the configuration information does NOT use these prefix bytes. FIELDNAME DESCRIPTION ipbroad is the IP address used on the ethernet cable to do a broadcast on that ether cable. Use the network number qualified form (NOT 255.255.255.255). ipname address of a name server, passed to MacIP programs. ipdebug address of the host allowed to run ddt. ipfile address of a file server, passed to MacIP programs. ipother four other IP addresses or long integers passed to MacIP programs. atnetet appletalk net number, ethertalk port; this field may be zero if you are not using ethertalk. Otherwise it should match the 'E' line that points to this kbox. ddprangestart is a short specifing the start of the UDP port range used to map well known udp ports to ddp "static assigned sockets" flags a long word of bit flags; see doc/rev0987 ipstatic the number of statically assigned MacIP addresses; read the 'doc/ip.at' document. ipdynamic the number of dynamically assigned MacIP addresses; the gateway uses a 'range' of IP addresses on the ether side; the number of addresses is 1+ipstatic+ipdynamic. atneta appletalk net number, localtalk port; note that this should be the same number as was specified on the 'K' line describing this kbox. atnete appletalk net number, appletalk-in-IP ether port; should match the number of the closest previous 'N' or 'H' line. In three of the fields, you are asked to specify the appletalk network numbers for the three different 'ports' (appletalk-forms) on the kbox: localtalk, appletalk-in-IP, and ethertalk. The localtalk and appletalk-in-IP network numbers are mandatory while the ethertalk network number is optional. To simplify configuration, you can specify "%n" in these fields. The atalkad daemon will then try to fill in each field with the correct appletalk network number. "%n" does this by following these rules: If %n is in the atnete field (e.g. refers to a appletalk-in-IP cable), then %n refers to the most recently seen "H" or "N" flagged entry that has the same network number (masked against 255.255.255.0) as the Kinetics box in question If %n is in the atneta field (e.g. refers to a localtalk network) then %n refers to the anet number of the current 'K' line. If %n is in the atnetet field (e.g. refers to a ethertalk network) then %n refers to the most recently seen "E" flagged entry that has the same ip address as the kinetics box in question. You can check your atalkatab by running atalkad in check mode by using the "-c" flag. "-c" with no arguments will read in the default atalkatab and then dump it in format more oriented to human perusal. This is useful for seeing if your "%n" entries match up to what you expected them to. "-c" also takes a file name as an argument that overrides the default atalkatab. Once /etc/atalkatab is complete, you should start the daemon, /etc/atalkad. You should be su for this. Check the log file /usr/adm/atalkalog to see if any errors were detected in parsing the database. Edit your /etc/rc.local to add a line to start atalkad whenever your administrator host boots. DDP START RANGE In April, 1988, the NIC assigned a range of ports for using by KIP for "static" or "well known" assigments. In particular, it assigned: 201 - AT-RMTP - AppleTalk Routing Maintenance 202 - AT-NBP - AppleTalk Name Binding 203 - AT-3 - AppleTalk Unused 204 - AT-ECHO - AppleTalk Echo 205 - AT-5 - AppleTalk Unused 206 - AT-ZIS - AppleTalk Zone Information 207 - AT-7 - AppleTalk Unused 208 - AT-8 - AppleTalk Unused for this purpose. KIP had been using the range starting at 768. The start range can now be specified in the ddprangestart configuration field. It is recommended that you use the new start range value of 200 if you can. A value of zero implies the old range starting at 768. CAP 5.0 allows the use of the new port range by installing the names in /etc/services for use by getservent. If you do one of these, then you must do the other. Following are the entries for /etc/services at-rtmp 201/udp # udp: rtmp at-nbp 202/udp # udp: nbp at-echo 204/udp # udp: echo at-zip 206/udp # udp: zip WARNING: future versions of KIP and CAP will default to the new mappings starting at 200. The old mappings are being used now until KIP and CAP get back into synchronization on this issue. ETHERTALK CONSIDERATIONS If you are using ethertalk, you will want to use the second group of eight lines in the sample atalkatab as your template. Note that the 'E' line points to the kbox that will be performing the ethertalk gateway function. If you have more than one kbox on a given ether cable, only ONE of them should have such an 'E' line. This is because there will be only ONE appletalk net number associated with that ethertalk cable and it must point to ONE kbox. (The kbox routing tables are such that one anet number can only point to a single gateway). [If you have other kboxes on the same ether cable, you CAN set the 'atnetet' field of those boxes to the anet number of the ethertalk. You would have to do this manually since the %n mechanism will not work. However note the following: Due to the way ethertalk hosts select a gateway (by listening to the last broadcast RTMP), the ethertalk host will be randomly selecting among the multiple kboxes. This situation is inherent in the appletalk protocol specifications.] EDIT /ETC/ATALK.LOCAL EACH UNIX host that wishes to use CAP utilities and libraries must have an /etc/atalk.local file. (Atalkad doesnt need CAP). Now that your departmental appletalk administrator has chosen appletalk net numbers for your local cables, you need to edit this information into /etc/atalk.local. This file looks like: # mynet mynode myzone 55.9 5 YourZoneName # bridgenet bridgenode bridgeIP 55.9 240 128.222.9.240 Just type in the appletalk net number for the UNIX's ether cable as the first number. The second number will be the low byte of the host's IP address. The third field is the local zone name. On the second (noncomment) line we give the address for the 'closest' kbox. The first and second numbers are the ANETE network number and node numbers (note that the anete node number is always the last byte of the ip address). The third number is the IP address of the kbox. (This can be a IP host name as well but since 4.2 BSD name lookup is very slow, we recommend putting just the number here). Note, it is important to use the ANETE network number when specifying the location of the Kinetics box since the anetet and aneta node numbers are not knowable in advance. The kbox is usually on the same ether cable as your CAP host, but it does not have to be. The CAP host can be on any ether cable, as long as there is an 'N' (or 'H' with atalkrd) line in atalkatab pointing to that cable (or host). SETUP GW.SREC AND PROMPT.CONFIG ON MAC DISK Each kbox must be downloaded with its program and minimal configuration information. These files plus the downloader must all exist on a Mac disk. The downloader program from Kinetics was previously called 'Prompt'. On their latest shipments, they have renamed it 'FastPath Manager'. In either case the current version number is 2.0. It also helps to have a copy of 'edit' or 'MockWrite' on the disk to customize the prompt.config file. So you need to use macput, efs, kermit, etc., to put the files gw.srec and prompt.config onto this disk. Here is what the sample prompt.config file looks like in this directory: * Config file for KFPS, KIP version, 10/86. * * A future version of the 'prompt' program will recognize * a line containing a 'dot format' address and convert those * four decimal byte values to four hex bytes(!) * * These bytes are ignored but must be left as placeholders: 0000 0000 FF FF FF 00 000000 000000 * Gateway name (in this example, "gw") 677700000000000000000000000000000000000000 * File name (in this example, "gw.srec"): 67772E737265630000000000000000000000000000 * reserved (this field should be 00FF): 00FF * * Start of 'mandatory' parameters, the minimum information that * must be supplied for the gateway to begin operation. * * IP address of myself, 'ipaddr' * 128.222.9.240 80de09f0 * IP addr of admin host * 128.222.9.5 80de0905 * IP addr of default route (nearest 'real' gateway) * 128.222.9.16 80de0910 * ethernet hardware addr of KFPS; * 080089 is the Kinetics manufacturer code, * remaining bytes are the serial number of your box. 080089 F00777 * next value is a flag, if it is '1234' the remainder * of this file is considered valid; any other value means * that the remaining parameters will be obtained from atalkad. 0000 What we do here at Stanford is make a XXX.config file version for each kbox, where XXX is replaced by the kbox name or address. Since all the 'prompt' parameters are supplied in this file, no typeins have to be done into the prompt dialog boxes. This simplifies the downloading procedure for operations staff. Here then is the procedure for downloading; note that all of the operations involving 'prompt' should allow no more than 30 seconds of 'idle' time for the gateway. Otherwise the gateway will just enter its automatic power up reboot sequence; not what you want. The instructions below are for prompt version 2.0; Kinetics may make some revisions/simplifications so these instructions may change slightly. (1) ensure the ethernet and appletalk cables are plugged in to the kbox. (2) power cycle the kbox. It is possible to avoid power cycling the kbox if you have version 3.0 or later of the EPROMs installed: use the Options menu item "Show EPROM Info" in version 2.0 or later of Prompt to ascertain this. Prior PROMs have a bug that makes this unreliable and in these cases it is best to cycle the power. (3) run 'prompt' on the Mac and select menu Gateways/Find Gateways. (4) press the RESET button. This will clear out any old programs; answer 'yes' to any 'are you sure' questions. (5) now do another Find Gateways. Also pull down menu Options/Show Diagnostics. This will enable any diagnostic messages from the gateway during loading to be visible. (6) using the menu, pull down File/Open Config File. Specify your XXX.config file. Don't be concerned that the dialog boxes showing 'appletalk zone name' and 'appletalk net number' look erroneous. This is because the 'prompt' program doesnt know the exact format of the XXX.config data used by KIP and misinterprets some of it. It is OK, only the dialog display is incorrect, the download operation will proceed as normal. DO NOT attempt to edit any of the dialog data by hand; it is only editable via the XXX.config file. (7) press the SEND CONFIG button; there will also be an acknowlegment message. (8) press the SEND LOAD button, this will start the download and a 'thermometer' will show the progress. (9) press GO, this will start the new code. You should see a diagnostic message at this time indicating that the gateway has correctly started up. It also shows the number of free buffers in the KFPS memory. If you are using version 2.0 or later of Prompt, you can use the "Options" menu item "Show Diagnostics" to watch for the initial "boot message" from KIP. Otherwise, if you have a 'peek' running on the appletalk (enable reception of RTMPs) you should see some gateway broadcasts startup in a moment. Also, if you look in atalkalog, you will see messages indicating that config and routing info has been sent to the new gateway. TEST GATEWAY WITH PING, DDT, CHOOSER. From UNIX you should be able get a response by sending an ICMP echo packet to the gateway. Use the 4.X BSD command 'ping IP_address'. If you have the ddt running you should be able to say 'ddt gw.sym IP_address', then 'main/'. Successive '/'s will open up following locations. On a Mac, run chooser and/or print some files on your LaserWriter to verify that the name binding protocol is working ok. Follow the same procedure for subsequent gateways. Chooser should now show the union of all your printers or other resources. ATALKAD GLOBAL OPERATIONS The admin daemon will reread its /etc/atalkatab file whenever the write date changes. But note that the file should rewritten in place --some editors relink the old file to filename.BAK, etc. (Note: this restriction was removed as of KIP revision 0188). The gateways only ask for config and routing info when they boot, so if you have changed this info, you must tell the daemon to force it out to all gateways in your domain. This is done by sending the running atalkad a special signal. Typing the command '/etc/atalkad route' will send new routing tables to all the gateways. Typing '/etc/atalkad boot' will cause all gateways to reload their config info AND routing tables. Note that a backround atalkad must be running; these commands just send a signal to that running daemon. So the rule might be, whenever you add or change the routing information in atalkatab (the lines that start in column 1), you should do an atalkad route. If you only change the kbox config info and are going to manually reboot that box, there is no need to tell everybody about it. However if you want to change the kbox config without leaving your chair, you'll have to reboot everybody with a atalkad boot. I suppose we should add a 'atalkad boot net#', to reconfigure a specific box, but we havent yet. INSTALL CAP OR KHOST See the installation document provided. CAP requires atalk.local! The biggest problem usually face is that the atalkatab specifications do not provide the proper routing. IP services seem to work, but CAP does not. Generally, watch out to make sure if you specify N1, N2, N3 routing lines that the resulting broadcast addresses are valid (see broadcast for more information). MAC IP PROGRAMS Several programs are available for IP communication on the Mac. The programs usually include services for 'telnet' (terminal connection and emulation) and 'ftp' (file transfer protocol). IP packages that we know of include: Stanford University SU-MacIP NCSA (Nat. Center for Supercomputing Appl. at U of Ill.) Telnet/FTP TOPS Telnet/FTP Phil Karn (KA9Q) TCP/IP package Some of these programs are assigned their IP addresses automatically by the gateway, so no configuration or customization files are necessary on your Mac disk. * SU-MacIP The Stanford MacIP is currently only being distributed on a (low cost, $50) license arrangement. For more information from the Stanford ACIS/Networking department you can email to: macip@ahwahnee.stanford.edu or send U. S. Mail to: SU-MacIP Stanford Univ. Information Resources, Networking Pine Hall Stanford, CA 94305 * NCSA Telnet For more information on the National Center for Supercomputing Applications (NCSA) Telnet program, please see the NCSA files in the <INFO-MAC> directory on SUMEX-AIM.STANFORD.EDU. They are under the name NCSA-*.*. The complete set of NCSA Telnet files for the Macintosh (and PC) is available via anonymous FTP from ftp.ncsa.uiuc.edu (128.174.20.50). On the NCSA host, the Mac files are in the subdirectory NCSA_Telnet/Mac.